package org.Yiran.timetale_re.item.rune.base;

import net.minecraft.world.entity.player.Player;
import net.minecraft.world.item.ItemStack;
import net.minecraft.world.level.Level;

/**
 * 符文能力接口
 * <p>
 * 该接口定义了符文的基本能力规范，所有符文实现都必须实现此接口。
 * 包含符文使用、tick更新、类型和分类等基本方法。
 * </p>
 */
public interface RuneAbility {
    
    // ============================== 符文使用方法 ==============================
    
    /**
     * 当符文被使用时调用
     * <p>
     * 此方法在符文被玩家激活使用时调用，实现具体的符文效果。
     * 例如：释放技能、生成实体、改变环境等一次性效果。
     * </p>
     * 
     * @param stack 符文物品堆
     * @param level 世界对象
     * @param player 使用符文的玩家
     */
    void onUse(ItemStack stack, Level level, Player player);
    
    // ============================== 符文更新方法 ==============================
    
    /**
     * 每个tick调用（用于持续效果）
     * <p>
     * 此方法每tick都会被调用，用于实现符文的持续效果。
     * 例如：持续治疗、持续伤害、状态效果维持等。
     * </p>
     * 
     * @param stack 符文物品堆
     * @param level 世界对象
     * @param player 持有符文的玩家
     */
    void onTick(ItemStack stack, Level level, Player player);
    
    // ============================== 符文属性方法 ==============================
    
    /**
     * 获取符文类型
     * <p>
     * 返回符文的具体类型标识符，用于区分不同的符文效果。
     * 例如："life"、"storm"、"thunder"等。
     * </p>
     * 
     * @return 符文类型字符串
     */
    String getType();
    
    /**
     * 获取符文分类
     * <p>
     * 返回符文的分类标识符，用于对符文进行分组。
     * 例如："functional"（功能类）、"amplification"（增幅类）、"throwable"（可投掷类）等。
     * </p>
     * 
     * @return 符文分类字符串
     */
    String getCategory();
    
    // ============================== 符文配置方法 ==============================
    
    /**
     * 获取冷却时间（tick）
     * <p>
     * 返回符文使用后的冷却时间，以tick为单位。
     * 默认值为1200tick（60秒）。
     * </p>
     * 
     * @return 冷却时间（tick单位）
     */
    default int getCooldown() {
        return 1200; // 默认60秒
    }
}